﻿<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">
<html>
	<head>
		<title>Stauffware.Essentials C# class library</title>
		<link href="../documentation/Stauffware.css" rel="StyleSheet" type="text/css" media="screen, print" />
	</head>
	<body>
		<div class="pageHdr" style="clear:both;">
			<table class="pageHdr"><tr class="pageHdr" valign="middle">
				<td class="crumb0"><a class="crumb0" href="..\_READ_ME_.html">Stauffware C#<br />Class Libraries</a></td>
				<td class="crumb2">&rarr; &nbsp; Essentials</td>
				<td class="crumb1">&rarr;&nbsp;READ_ME</td>
			</tr></table>
			<br />

			<table class="navbar"><tr valign="middle">
				<td><a href="#Contents">Contents</a></td>
				<td>&ensp;&bull;&ensp;</td>
				<td><a href="#Prerequisites">Prerequisites</a></td>
				<td>&ensp;&bull;&ensp;</td>
				<td><a href="#HowToBuildIt">How to Build It</a></td>
				<td>&ensp;&bull;&ensp;</td>
				<td><a href="documentation/IssuesAndHistory.html#KnownIssues">Known<br />Issues</a></td>
				<td>&ensp;&bull;&ensp;</td>
				<td><a href="documentation/IssuesAndHistory.html#RevisionHistory">Revision<br />History</a></td>
			</tr></table>
		</div>

		<a name="Contents" />
		<h1>Contents</h1>

		<h2>The Class Library</h2>

		Details in <a href="documentation/Overview.html">documentation/Overview.html</a>.

		<h3>Other Stuff</h3>
		UnitTests - a set of unit tests, written using NUnit.
		<p />
		<b>Essentials.sln</b> &ndash; the Visual Studio solution file.
		
		<a name="Prerequisites" />
		<h1>Prerequisites</h1>
		
		<dl>
			<dt><b>Microsoft .Net Runtime 4.0</b></dt>
			<dd></dd>
			<dt><b>Microsoft Visual Studio</b></dt>
			<dd>These libraries are maintained using a commercial (expensive)
				edition of Visual Studio.  They have also been successfully built using the
				free edition <a href="http://www.microsoft.com/visualstudio/en-us/products/2010-editions/visual-csharp-express">Visual C# 2010 Express</a>.
				As of this writing, nobody has tried building them under 
				<a href="http://en.wikipedia.org/wiki/Mono_%28software%29">Mono</a>.
				</dd>
			<dt><b>NUnit</b></dt>
			<dd>This is a popular open-source unit testing framework,
				needed only for the Stauffware unit tests.  You can download it here:
				<a href="http://www.nunit.org">www.nunit.org</a>.
				<p />
				<b>Note:</b> the unit test project runs its tests by way of a Post-Build Event.
				The command therein locates the NUnit installation through the environment
				variable <code>NUNIT</code>, in order to avoid using a machine-dependent path.
				You must set this environment to the directory containing 
				<code>nunit-console.exe</code>; for example:<br />
				<code>&nbsp; &nbsp; &nbsp;set NUNIT=c:\Program Files\NUnit 2.5.10\bin\net-2.0</code><br />
				Do not include quotes in this path to compensate for the spaces; 
				the Post-Build Event takes care of that.<br/>
				<i>NOTE:</i> After setting this environment variable, you must restart Visual Studio.
				</dd>
		</dl>

		<a name="HowToBuildIt" />
		<h1>How to Build It</h1>

			<ol>
				<li>Download and unpack (as needed) the sources into a directory of your choosing.</li>
				<li>Open Essentials.sln using Microsoft Visual Studio.</li>
				<li>From the main menu bar, select "Build | Build Solution" or "Build | Rebuild Solution".</li>
				<li>The unit tests will have been run automatically as part of the build process.
					If any of them failed, the build should fail.  The build may also fail if it can't
					find NUnit.  The most common errors related to NUnit are:
					<dl>
						<dt><code>&bull; The command ""%NUNIT%\nunit-console" <i>blah, blah, blah</i>" exited with code 9009.</code></dt>
						<dd>The "9009" error means that "nunit-console.exe" couldn't be found, as a peek at the build output should reveal:<br />
							<code>PostBuildEvent:<br />
								"%NUNIT%\nunit-console" <i>blah, blah, blah</i>\UnitTests.dll <i>blah, blah, blah</i><br />
								'"c:\Program Files\NUnit 2.5.10\bin\net-2.0\nunit-console"' is not recognized 
								as an internal or external command, operable program or batch file.</code><br />
							The most likely reasons for getting this error are (a) you didn't install NUnit, 
							(b) you didn't set the "NUNIT" environment variable, or
							(c) you didn't restart Visual Studio after setting the environment variable.
							</dd>
						<dt><code>&bull; The command ""%NUNIT%\nunit-console" <i>blah, blah, blah</i>" exited with code 1.</code></dt>
						<dd>The "1" error means that one or more tests failed.  For details, examine the build output.</dd>
					</dl>				
					</li>
				<li>A few of the DateUtils tests require manual verification; see the build log.</li>
			</ol>

		<div class="license">
			<p>Copyright 2011 Edward L. Stauff. &nbsp;	Contact: <a href="mailto:EdStauff@gmail.com">EdStauff@gmail.com</a></p>
			<p>
				This file is part of the "Stauffware.Essentials" library.             
				"Stauffware.Essentials" is free software: you can redistribute it     
				and/or modify it under the terms of the GNU Lesser Public License as published     
				by the Free Software Foundation, either version 3 of the License, or (at your      
				option) any later version.                                                         
			</p><p>
				"Stauffware.Essentials" is distributed in the hope that it will       
				be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of          
				MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU Lesser           
				Public License for more details.                                                   
			</p><p>
				You should have received a copy of the GNU Lesser Public License along with        
				"Stauffware.Essentials".  If not, see 
				<a href="http://www.gnu.org/licenses/">http://www.gnu.org/licenses/</a>. 
			</p>
		</div>
	</body>
</html>

